home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / ADA / GNAT / !gcc / gnat / Bugs next >
Text File  |  1996-11-09  |  10KB  |  218 lines
  1. Reporting Bugs
  2. **************
  3.  
  4.    Your bug reports play an essential role in making GNAT reliable.
  5.  
  6.    When you encounter a problem, the first thing to do is to see if it
  7. is already known.  If it isn't known, then you should report the problem.
  8.  
  9.    Reporting a bug may help you by bringing a solution to your problem,
  10. or it may not.  In any case, the principal function of a bug report
  11. is to help the entire community by making the next version of GNAT
  12. work better.  Bug reports are your contribution to the maintenance of
  13. GNAT and should be sent by e-mail to gnat@arcangel.dircon.co.uk. If you
  14. don't have access to e-mail, then post them to me at the address in the
  15. !gcc.gnat.Help file.
  16.  
  17.    Since the maintainers are very overloaded, we cannot respond to every
  18. bug report, although we will try to cure as many as possible.
  19.  
  20.    In order for a bug report to serve its purpose, you must include the
  21. information that makes for fixing the bug.
  22.  
  23. Have You Found a Bug?
  24. =====================
  25.  
  26.    If you are not sure whether you have found a bug, here are some
  27. guidelines:
  28.  
  29.    * If the compiler gets a fatal signal, for any input whatever, that
  30.      is a compiler bug.  Reliable compilers never crash.
  31.  
  32.    * If the compiler produces invalid assembly code, for any input
  33.      whatever (except an `asm' statement), that is a compiler bug,
  34.      unless the compiler reports errors (not just warnings) which would
  35.      ordinarily prevent the assembler from being run.
  36.  
  37.    * If the compiler produces valid assembly code that does not
  38.      correctly execute the input source code, that is a compiler bug.
  39.  
  40.      However, you must double-check to make sure, because you may have an
  41.      erroneous program which doesn't raise PROGRAM_ERROR.
  42.      
  43.      After you have localized the error to a single source line, it
  44.      should be easy to check for these things.  If your program is
  45.      correct and well defined, you have found a compiler bug.
  46.  
  47.    * If the compiler produces an error message for valid input, that is
  48.      a compiler bug.
  49.  
  50.    * If the compiler does not produce an error message for invalid
  51.      input, that is a compiler bug.  However, you should note that your
  52.      idea of "invalid input" might be my idea of "an extension" or
  53.      "support for traditional practice".
  54.  
  55.    * If you are an experienced user of Ada compilers, your suggestions
  56.      for improvement of GNAT are welcome in any case.
  57.  
  58. Where to Report Bugs
  59. ====================
  60.  
  61.    Send bug reports for GNAT to gnat@arcangel.dircon.co.uk.
  62.  
  63.    Send bug reports for GNU C++ to nickb@digibank.demon.co.uk.  If your
  64. bug involves the C++ class library libg++, send mail to
  65. bug-lib-g++@prep.ai.mit.edu.  If you're not sure, you can send the
  66. bug report to both addresses.
  67.  
  68.    *Do not send bug reports to `help-gcc@prep.ai.mit.edu' or to the
  69. newsgroup `gnu.gcc.help'.* Most users of GNU CC do not want to receive
  70. bug reports.
  71.  
  72.  
  73. How to Report Bugs
  74. ==================
  75.  
  76.    The fundamental principle of reporting bugs usefully is this:
  77. *report all the facts*.  If you are not sure whether to state a fact or
  78. leave it out, state it!
  79.  
  80.    Often people omit facts because they think they know what causes the
  81. problem and they conclude that some details don't matter.  Thus, you
  82. might assume that the name of the variable you use in an example does
  83. not matter.  Well, probably it doesn't, but one cannot be sure.
  84. Perhaps the bug is a stray memory reference which happens to fetch from
  85. the location where that name is stored in memory; perhaps, if the name
  86. were different, the contents of that location would fool the compiler
  87. into doing the right thing despite the bug.  Play it safe and give a
  88. specific, complete example.  That is the easiest thing for you to do,
  89. and the most helpful.
  90.  
  91.    Keep in mind that the purpose of a bug report is to enable someone to
  92. fix the bug if it is not known.  It isn't very important what happens if
  93. the bug is already known.  Therefore, always write your bug reports on
  94. the assumption that the bug is not known.
  95.  
  96.    Sometimes people give a few sketchy facts and ask, "Does this ring a
  97. bell?"  This cannot help us fix a bug, so it is basically useless.  We
  98. respond by asking for enough details to enable us to investigate.  You
  99. might as well expedite matters by sending them to begin with.
  100.  
  101.    Try to make your bug report self-contained.  If we have to ask you
  102. for more information, it is best if you include all the previous
  103. information in your response, as well as the information that was
  104. missing.
  105.  
  106.    Please report each bug in a separate message.  This makes it easier
  107. for us to track which bugs have been fixed and to forward your bugs
  108. reports to the appropriate maintainer.
  109.  
  110.    To enable someone to investigate the bug, you should include all
  111. these things:
  112.  
  113.    * The version of GNAT.  You can get this by running it with the
  114.      `-v' option.
  115.  
  116.      Without this, we won't know whether there is any point in looking
  117.      for the bug in the current version of GNAT.
  118.  
  119.    * A complete input file that will reproduce the bug.  For a report
  120.      that contains multiple separate compilation units, and hence
  121.      multiple files, submit them in the form of a single file that is
  122.      acceptable input to gnatchop, i.e., contains no non-Ada text. If you
  123.      use banners to separate the files, make sure they are composed
  124.      entirely of blank lines or Ada comments.
  125.      
  126.      A single statement is not enough of an example.  In order to
  127.      compile it, it must be embedded in a complete file of compiler
  128.      input; and the bug might depend on the details of how this is done.
  129.  
  130.      Without a real example one can compile, all anyone can do about
  131.      your bug report is wish you luck.  It would be futile to try to
  132.      guess how to provoke the bug.  For example, bugs in register
  133.      allocation and reloading frequently depend on every little detail
  134.      of the function they happen in.
  135.  
  136.      If you want to be maximally helpful, try to reduce your example to a
  137.      simple one but DON'T spend too much time doing this.  Especially when
  138.      you are reporting a blow up during compilation, rather than bad code
  139.      generated, we can in practice work with big sources if you have
  140.      trouble narrowing things down.
  141.  
  142.    * The command arguments you gave GNAT or one of the GNAT tools to
  143.      compile that example and observe the bug.  For example, did you use
  144.      `-O'?  To guarantee you won't omit something important, list all the
  145.      options.
  146.  
  147.      If we were to try to guess the arguments, we would probably guess
  148.      wrong and then we would not encounter the bug.
  149.  
  150.    * The type of machine you are using, and the operating system name
  151.      and version number.
  152.  
  153.    * A description of what behavior you observe that you believe is
  154.      incorrect.  For example, "The compiler gets a fatal signal," or,
  155.      "The assembler instruction at line 208 in the output is incorrect."
  156.  
  157.      Of course, if the bug is that the compiler gets a fatal signal,
  158.      then one can't miss it.  But if the bug is incorrect output, the
  159.      maintainer might not notice unless it is glaringly wrong.  None of
  160.      us has time to study all the assembler code from a 50-line Ada
  161.      program just on the chance that one instruction might be wrong.
  162.      We need *you* to do this part!
  163.  
  164.      Even if the problem you experience is a fatal signal, you should
  165.      still say so explicitly.  Suppose something strange is going on,
  166.      such as you have encountered a bug in the C library on your system.
  167.      (This has happened!)  Your copy might crash and the copy here would
  168.      not.  If you said to expect a crash, then when the compiler here fails
  169.      to crash, we would know that the bug was not happening.  If you don't
  170.      say to expect a crash, then we would not know whether the bug was
  171.      happening.  We would not be able to draw any conclusion from our
  172.      observations.
  173.  
  174.      Often the observed symptom is incorrect output when your program
  175.      is run.  Sad to say, this is not enough information unless the
  176.      program is short and simple.  None of us has time to study a large
  177.      program to figure out how it would work if compiled correctly,
  178.      much less which line of it was compiled wrong.  So you will have
  179.      to do that.  Tell us which source line it is, and what incorrect
  180.      result happens when that line is executed.  A person who
  181.      understands the program can find this as easily as finding a bug
  182.      in the program itself.
  183.  
  184.      If a bug involves incorrect operation of the generated code, then
  185.      the first thing the program should do is to output a line
  186.      indicating the expected output or behavior.  If at all possible, do
  187.      a test later on that prints out "passed" or "failed" depending on
  188.      the behavior. Of course it may not always be possible to structure
  189.      a test this way, but that's the most  convenient form (for obvious
  190.      reasons!)
  191.  
  192.    Here are some things that are not necessary:
  193.  
  194.    * A description of the envelope of the bug.
  195.  
  196.      Often people who encounter a bug spend a lot of time investigating
  197.      which changes to the input file will make the bug go away and which
  198.      changes will not affect it.
  199.  
  200.      This is often time consuming and not very useful, because the way
  201.      we will find the bug is by running a single example under the
  202.      debugger with breakpoints, not by pure deduction from a series of
  203.      examples.  You might as well save your time for something else.
  204.  
  205.      Of course, if you can find a simpler example to report *instead* of
  206.      the original one, that is a convenience.  Errors in the output
  207.      will be easier to spot, running under the debugger will take less
  208.      time, etc.  Most GNAT bugs involve just one function, so the
  209.      most straightforward way to simplify an example is to delete all
  210.      the function definitions except the one where the bug occurs.
  211.      Those earlier in the file may be replaced by external declarations
  212.      if the crucial function depends on them.  (Exception: inline
  213.      functions may affect compilation of functions defined later in the
  214.      file.)
  215.  
  216.      However, simplification is not vital; if you don't want to do this,
  217.      report the bug anyway and send the entire test case you used.
  218.